<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="http://www.petercorke.com/RVC/common/toolboxhelp.css">
    <title>M-File Help: plot_vehicle</title>
  </head>
  <body>
  <table border="0" cellspacing="0" width="100%">
    <tr class="subheader">
      <td class="headertitle">M-File Help: plot_vehicle</td>
      <td class="subheader-left"><a href="matlab:open plot_vehicle">View code for plot_vehicle</a></td>
    </tr>
  </table>
<h1>plot_vehicle</h1><p><span class="helptopic">Draw mobile robot pose</span></p><p>
<span style="color:red">plot_vehicle</span>(<strong>x</strong>,<strong>options</strong>) draws an oriented triangle to represent the pose
of a mobile robot moving in a planar world.  The pose <strong>x</strong> (1x3) = [x,y,theta].
If <strong>x</strong> is a matrix (Nx3) then an animation of the robot motion is shown and
animated at the specified frame rate.

</p>
<h2>Image mode</h2>
<p>
Create a structure with the following elements and pass it with the
'model' option.

</p>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> image</td> <td>an RGB image (HxWx3)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> alpha</td> <td>an alpha plane (HxW) with pixels 0 if transparent</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> rotation</td> <td>image rotation in degrees required for front to pointing to the right</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> centre</td> <td>image coordinate (U,V) of the centre of the back axle</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> length</td> <td>length of the car in real-world units</td></tr>
</table>
<h2>Animation mode</h2>
<p>
<strong>H</strong> = <span style="color:red">plot_vehicle</span>(<strong>x</strong>,<strong>options</strong>) as above draws the robot and returns a handle.

</p>
<p>
<span style="color:red">plot_vehicle</span>(<strong>x</strong>, 'handle', <strong>H</strong>) updates the pose <strong>x</strong> (1x3) of the previously drawn
robot.

</p>
<h2>Options</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1">'scale', S</td> <td>draw vehicle with length S x maximum axis dimension (default
1/60)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'size', S</td> <td>draw vehicle with length S</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'fillcolor', F</td> <td>the color of the circle's interior, MATLAB color spec</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'alpha', A</td> <td>transparency of the filled circle: 0=transparent, 1=solid</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'box'</td> <td>draw a box shape (default is triangle)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'fps', F</td> <td>animate at F frames per second (default 10)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'image', I</td> <td>use an image to represent the robot pose</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'retain'</td> <td>when X (Nx3) then retain the robots, leaving a trail</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'model', M</td> <td>animate an image of the vehicle.  M is a structure with
elements: image, alpha, rotation (deg), centre (pix), length (m).</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'axis', h</td> <td>handle of axis or UIAxis to draw into (default is current axis)</td></tr>
</table>
<h2>Example</h2>
<pre style="width: 90%%;" class="examples">
[car.image,~,car.alpha]&nbsp;=&nbsp;imread('car2.png');&nbsp;&nbsp;%&nbsp;image&nbsp;and&nbsp;alpha&nbsp;layer
car.rotation&nbsp;=&nbsp;180;&nbsp;&nbsp;%&nbsp;image&nbsp;rotation&nbsp;to&nbsp;align&nbsp;front&nbsp;with&nbsp;world&nbsp;x-axis
car.centre&nbsp;=&nbsp;[648;&nbsp;173];&nbsp;%&nbsp;image&nbsp;coordinates&nbsp;of&nbsp;centre&nbsp;of&nbsp;the&nbsp;back&nbsp;wheels
car.length&nbsp;=&nbsp;4.2;&nbsp;%&nbsp;real&nbsp;world&nbsp;length&nbsp;for&nbsp;scaling&nbsp;(guess)
h&nbsp;=&nbsp;plot_vehicle(x,&nbsp;'model',&nbsp;car)&nbsp;&nbsp;%&nbsp;draw&nbsp;car&nbsp;at&nbsp;configuration&nbsp;x
plot_vehicle(x,&nbsp;'handle',&nbsp;h)&nbsp;&nbsp;%&nbsp;animate&nbsp;car&nbsp;to&nbsp;configuration&nbsp;x
</pre>
<h2>Notes</h2>
<ul>
  <li>The vehicle is drawn relative to the size of the axes, so set them
first using axis().</li>
  <li>For backward compatibility, 'fill', is a synonym for 'fillcolor'</li>
  <li>For the 'model' option, you provide a monochrome or color image of the
vehicle.  Optionally you can provide an alpha mask (0=transparent).
Specify the reference point on the vehicle as the (x,y) pixel
coordinate within the image.  Specify the rotation, in degrees, so that
the car's front points to the right.  Finally specify a length of the
car, the image is scaled to be that length in the plot.</li>
  <li>Set 'fps' to Inf to have zero pause</li>
</ul>
<p>
See also Vehicle.plot, plot_poly, demos/car_animation

</p>
<hr>

<table border="0" width="100%" cellpadding="0" cellspacing="0">
  <tr class="subheader" valign="top"><td>&nbsp;</td></tr></table>
<p class="copy">&copy; 1990-2014 Peter Corke.</p>
</body></html>